.TH lha_form 1 "2 November 2008" "TrueCL Commands"

.SH NAME
lha_form \- Form a cluster / add nodes to a running cluster

.SH SYNOPSES
.TS
l l.
clreq	[\fB--join\fP] [\fB--nodes\fP \fIa,...\fP] [\fB--force\fP] [\fB-timeout\fP \fIN\fP]
	[\fB--formtime\fP \fIN\fP] [\fB--debug\fP|\fB--verbose\fP|\fB--quiet\fP|\fB--silent\fP]
	[\fB--lwidth\fP \fIN\fP]
.TE

.SH DESCRIPTION
The \fIlha_form(1)\fP command is used to initiate the formation of a new cluster,
or allow other nodes to join an already active cluster. 

.SH ARGUMENTS
.TP 8
--join
If this is not specified the command will attempt to form a new cluster with
whatever cluster the current machine belongs to. If a cluster is already
running and this argument is not specified the command will abort with an
error.

If this argument is specified, but the cluster is not currently running, 
then again an error will be raised.

By default when this argument is used all nodes that are contactable that
are not currently part of the active cluster will be assumed to want to
join the cluster. If this is not required then use of the \fB--nodes\fP
argument is necessary.

.TP
--nodes
This is used to specify a comma-separated list of nodes to form the
new cluster or join the existing cluster. If this argument is not specified
then all nodes are assumed to wish to be part of the cluster. 

This argument is typically used if certain nodes are known to be down and
waiting for the 'formtime' period to elapse is not desirable. The order of
the nodes specified is not important.
.TP
--force
This argument allows the cluster formation to take place even if not all
nodes respond to the request to form a cluster. This argument must also be
used if the \fB--nodes\fP option is used and allowing the cluster to form
without all the specified nodes is desired.
.TP
--timeout
The amount of time to wait for a node to respond to a request to
indicate whether it is alive or not. Defaults to 30 seconds if not
specified.
.TP
--formtime
Specifies the amount of time to wait for the nodes to join or form the
cluster. This differs subtly from the \fB--timeout\fP argument since that
handles the timeout for individual requests, where this covers for formation
as a whole.

Typically \fB--formtime\fP is at least twice the value of \fB--timeout\fP.

If this argument is not specified it defaults to the value given for the 
cluster global setting 'formtime' [see the \fIlha_globals(5)\fP man
page for more details].
.TP
--debug
Start the cluster daemons in debug mode - the log files for each of the 
daemons will produce significantly more output than normal. This is not 
typically required and should only be done if problems in cluster formation
occur.
.TP
--verbose
Verbose mode generates a sensible amount of output to standard output to 
show the progress of cluster formation. This is the recommended flag if
the administrator wishes to see any output.
.TP
--quiet
This will only produce errors and warnings on the standard output device.
.TP
--silent
Only produce output if fatal errors occurs during cluster formation.

.SH OUTPUT
In verbose mode the utility will show the cluster formation in several distinct
phases. It will initially attempt to see which daemons are running and which 
nodes are contactable and then show a summary as it requires these to start.

It will then wait for the required supplementary daemons to start and 
if successfully the necessary cluster daemons will be started and then the
cluster will negotiate which node will become the master and show it once the
formation [or joining] has been completed successfully.

.SH EXIT CODES
If the cluster forms as expected, or the required nodes join the cluster
then a '0' return code [for successful will be given]. If the operations
fails completely a failure return code of '1' will occur. 

It should be noted that if the result is partially successful a return
code of '0' will occur if at least one node formed or joined the cluster.

.SH FILES
The utility uses standard error and output for all messages. Each of the
daemons use separate log files, the volume of output depending on which
of the verbosity flags are given on the command line. The table below 
summarizes the available logs for the standard daemons started by the
\fBlha_form(1)\fP command:

.TS
l l.
clusterd.log	All cluster daemon output/errors.
hbd.log	All Heartbeat daemon output/errors.
lockd.log	All Lock daemon output/errors.
mond.log	All Monitor daemon output/errors.
netd.log	All Network daemon output/errors.
statd.log	All Status daemon output/errors.
syncd.log	All Synchronize daemon output/errors.
.TE

All the files are written to the directory \fBTRUECL_LOG\fP, as
defined in the environment. If any output is generated outside of the standard
logging facilities [such as uncaught errors], then a file called "daemon.stdout"
or "daemon.stderr" will be written to in the same directory.

.SH NOTES
This command is typically only run occasionally when a new cluster needs to be
formed or further nodes are added back into the cluster, or are newly added
to an existing cluster. It is not recommended that this tool is run 
automatically on machine boot.

.SH AUTHOR
The TrueCL software was written by Simon Edwards, (C) 2006-2008, working
for Advantsys Computer Services Ltd - www.advantsys.co.uk.

.SH SEE ALSO
.BR lha_dissolve(1),
.BR lha_stopnode(1)

.SH AVAILABILITY
This utility was specifically written under the GNU GPL license and as required
by such software comes with \fIno warranty or guarantee of any kind\fP. For
more information, please see the following page: truecl.advantsys.co.uk.

